Evolution of this website

I created my first personal website in 2016, I thought it was a good opportunity for me to practice my writing and communication skills. Since then this website has gone through many iterations to arrive at this live version.

First version

The first version was powered by a custom Java 7 EE back-end which featured a custom CMS (Content Management System). Entire website was managed in the Admin view, hidden behind a login. There you could edit the posts directly in the custom HTML editor. Here's what it looked like:

This system was fine, but it always felt unstable because all editing was done in the browser. Even though I had implemented an automatic save, which saved the post every 5 seconds, I always felt uneasy about editing long posts with it.

No more web editor

Having learned from that, my next website featured the same custom CMS, but this time I had a built a desktop Java application to edit the HTML. Which I soon realized was a waste of time since existing text editors are much better at editing HTML than what I had built. All I needed was a few snippets to make the custom elements easier to write and it was fine.

However, after a while, writing HTML for posts became quite tedious and not so reliable. I wanted to write so much, but every time I wanted to write something I had this mountain of HTML to get through. I eventually burned out and archived the site.

Time to get Rusty

Fast forward to 2019, I jumped on the Rust hype train and got the "Crab Book". After a lot of practice I felt comfortable enough with my Rust skills and so I went server shopping. When the search reached its end, I landed on Actix, which is what I used for my website i going forward.

I painstakingly re-implemented my old Java CMS in Rust. This also gave me the chance to improve upon the CMS. Instead of writing HTML by hand like some caveman, I wanted to write Markdown. So I implemented a small Markdown parser in Rust and made it output HTML.

The front-end was written in React because that's what I was the most familiar with. I should also mention I ditched React for Svelte, 3 weeks into the project. This was my Rust phase, so it's only natural I rewrote the same code 10 times.

At this time I also developed the minimalist style, similar to one which is still used today. Here's how an older post looked like:

This time writer experience was much better because Markdown is a lot easier to write than HTML, and updating the website was much simpler than before. However, the back-end was needlessly complicated and adding new features was a Herculean effort.

Moving away from SPA-s

Up to this point all of my blogs were SPA's (Single Page Application's), which essentially means you do not reload the website every time the URL is changed, instead you dynamically fetch and update the content of the page. The benefit of this is supposed to be smoother experience on the user side. The disadvantage of this approach is a much more complicated website.

My SPA client solution was relatively simple, because I wrote the router myself instead of using some popular ones used with React or Svelte. The back-end was needlessly complicated, because it was written in Rust and there was practically no benefit to using Rust here over something simpler like Go.

As a result, changing things was incredibly difficult and this caused me to settle for less or handle more features on the client-side. Ultimately this caused my relatively simple SPA client to become a complex bag of bloat which nullified all the benefits of doing SPA.

HUGO

After a couple of months I decided to archive this project and start over with HUGO. Which is a static website generator written in Go.

This was by far the best experience on both ends. Writing was just Markdown and client had exactly 0 lines of JavaScript which made it faster for posts to load and it removed any opportunity for errors on that end. Customization was relatively straight forward, and server only needed to re-generate the HTML when the release branch changed.

So everything was fine, right? Yes, but actually no. I started to dislike Markdown because common things such as `inline_code`, (Link)[https....] are rather annoying to write. This is made even more difficult when you introduce HUGO shortcodes.

Dark_Matter

In 2020 I started thinking about a custom "documentation format" which would be easier for me to read in its source form and one which would make common elements really easy to express. I also knew that I did not need all of the Markdown elements, so I could afford to make it a lot simpler.

So now I have it. Dark Matter (.dm) is a custom documentation format, which is essentially a simpler version of Markdown. This is what it looks like:

name: example
date: 2024-01-01
desc: This part is the metadata, useful to the Dark_Matter compiler

# Heading 1

    Paragraph with { inline_code } and --emphasis-- and perhaps a [Link, filip-gacina.me]
    to some website. This is still the same paragraph.

    This is a new paragraph, as well as:
    - A list
    - Of things

## Heading 2

    This may be a technical blog, so we need:

    .cxx
        // block of C++ code:
        int main(int argc, char** argv) {
            return 0;
        }

    but we also want an image:

    .dm_figure
        src: /img/rat.jpg
        alt: A rat on the keyboard

    As you can see, code blocks are really extensible. This for the most part is all that is
    needed, but we can also have a horizontal rule, because it's useful sometime:

    ===

I personally find this much easier to read than Markdown, and it can produce the same HTML as Markdown. In fact, this website is generated with Dark_Matter. Source of this website looks exactly like the text above. I give Dark_Matter compiler the root directory in which to look for .dm files and it will go through those recursively and generate the entire website.

It's also able to minify CSS, and optionally embed that CSS in the generated HTML files in order to avoid having to load a separate CSS file for each post. To make the writer experience better I also made it auto-format any .dm file and then wrote a simple Sublime Text plugin in Python to make this happen automatically on save.

Additionally Dark_Matter will check for any mistakes and report them, meaning you don't have to look at output to know if you made errors. This is also integrated into Sublime Text, and it's another thing which makes the writer experience better.

For production any server will do, with some simple CI to pull the latest release branch. It's trivial to setup. For my "development server" I use Python to serve the files from the output directory on localhost:8000, like so:

cd output && python -m http.server

I wrote Dark_Matter in Jai. On the benchmark project it's able to generate an entire site consisting of 128 posts, where posts average 1000 words, from scratch, in ~210ms. It's multi threaded, here's a fun post about that: Multithreading with global state. This number will likely go down, but at the time of writing I only have ~20 posts, so it only takes me 17ms to rebuild from scratch.

Conclusion

When I started writing, I enjoyed using as many complex tools as possible, I felt proud of taming that complexity and my website style also reflected that. Luckily over time I realized most of this complexity is not necessary. So, I started getting rid of it all, piece by piece and my website style reflected this too.

The only purpose of a blog site is to display text in a readable manner to people who want to read it. It does not need a database, it does not need dynamic loading of content, it does not need animations, all it needs is HTML and some CSS to make it bearable for computer goblins.

All of the complexity of this website is contained within 1 tool - Dark_Matter, over which I have complete control. I use the same text editor that I use for everything else and my users get a small HTML document which will download fast even on slow networks. I have finally achieved the perfect writing experience and the perfect user experience (In my humble and biased opinion).